WebWork - Tags

Within the form tags, there are two classes of tags: the form tag itself, and all other tags, which make up the individual form elements. This is important as the behavior of the form tag itself is different than that of the elements enclosed within it. Before we go provide a reference for all the form tags, including the form tag itself, we must outline some general characteristics first.

Please make sure you have read the Tag Syntax document and understand how tag attribute syntax works.

Form Tag Themes

As previously noted in Themes and Templates, the HTML Tags (which includes Form Tags) are all driven by templates. Templates are grouped together to form themes. By default, WebWork provides three themes:

Remember: the xhtml theme renders out a two-column table. If you need a different layout, we highly recommend that you do not write your own HTML, but rather create your own theme or utilize the simple theme.

The downside of using the simple theme is that it doesn't support as many of the attributes that the other themes do. For example, the label attribute does nothing in the simple theme. Similarly, the functionality offered by the simple theme is much less than that of the xhtml and ajax themes: the automatic display of error messages is not supported.

Common Attributes

All the form tags extend the UIBean class. This base class generally common attributes, grouped in to three classes: templated-related, javascript-related, and general attributes. We won't document what these attributes do here as that is taken care of in each individual tag's reference. However, it is a good idea to familiarize yourself with the structure of the UI tags and what attributes are available for all tags.

In addition to these attributes, a special attribute exists for all form element tags: form(ie: ${parameters.form}). This represents the parameters used to render the form tag and allows you to provide interaction between your form elements and the form itself. For example, in a template you could access the form's ID by calling ${parameters.form.id}.

Template-Related Attributes

Attribute	Theme	Data Types	Description
templateDir	n/a	String	define the template directory
theme	n/a	String	define the theme name
template	n/a	String	define the template name

Javascript-Related Attributes

Attribute	Theme	Data Types	Description
onclick	simple	String	html javascript onclick attribute
ondbclick	simple	String	html javascript ondbclick attribute
onmousedown	simple	String	html javascript onmousedown attribute
onmouseup	simple	String	html javascript onmouseup attribute
onmouseover	simple	String	html javascript onmouseover attribute
onmouseout	simple	String	html javascript onmouseout attribute
onfocus	simple	String	html javascript onfocus attribute
onblur	simple	String	html javascript onblur attribute
onkeypress	simple	String	html javascript onkeypress attribute
onkeyup	simple	String	html javascript onkeyup attribute
onkeydown	simple	String	html javascript onkeydown attribute
onselect	simple	String	html javascript onselect attribute
onchange	simple	String	html javascript onchange attribute

Tooltip Related Attributes

Attribute	Data Type	Default	Description
tooltip	String	none	Set the tooltip of this particular component
tooltipIcon	String	/webwork/static/tooltip/tooltip.gif	The url to the tooltip icon
tooltipAboveMousePointer	Boolean	false	Places the tooltip above the mousepointer. Additionally applied the tooltipOffseY allows to set the vertical distance from the mousepointer.
tooltipBgColor	String	#e6ecff	Background color of the tooltip.
tooltipBgImg	String	none	Background image.
tooltipBorderWidth	String	1	Width of tooltip border.
tooltipBorderColor	String	#003399	Background color of the tooltip
tooltipDelay	String	500	Tooltip shows up after the specified timeout (miliseconds). A behavior similar to that of OS based tooltips.
tooltipFixCoordinateX	String	not specified	Fixes the tooltip to the X co-ordinates specified. Useful for example if combined with tooltipSticky attribute.
tooltipFixCoordinateY	String	not specified	Fixes the tooltip to the Y co-ordinates specified. Useful for example if combined with tooltipSticky attribute.
tooltipFontColor	String	#000066	Font color.
tooltipFontFace	String	arial,helvetica,sans-serif	Font face/family eg. verdana,geneva,sans-serif
tooltipFontSize	String	11px	Font size + unit eg. 30px
tooltipFontWeight	String	normal	Font weight. either normal or bold
tooltipLeftOfMousePointer	Boolean	false	Tooltip positioned on the left side of the mousepointer
tooltipOffsetX	String	12	Horizontal offset from mouse-pointer.
tooltipOffsetY	String	15	Vertical offset from mouse-pointer.
tooltipOpacity	String	100	Transparency of tooltip. Opacity is the opposite of transparency. Value must be a number between 0 (fully transparent) and 100 (opaque, no transparency). Not (yet) supported by Opera.
tooltipPadding	String	3	Inner spacing, ie. the spacing between border and content, for instance text or image(s)
tooltipShadowColor	String	#cccccc	Creates shadow with the specified color.
tooltipShadowWidth	String	5	Creates shodow with the specified width (offset).
tooltipStatic	Boolean	false	Like OS-based tooltips, the tooltip doesn't follow the movements of the mouse pointer.
tooltipSticky	Boolean	false	The tooltip stays fixed on its inital position until anohter tooltip is activated, or the user clicks on the document.
tooltipStayAppearTime	String	0	Specifies a time span in miliseconds after which the tooltip disappears, even if the mousepointer is still on the concerned HTML element, with value <=0 it acts as if no time span is defined
tooltipTextAlign	String	left	Aligns the text of both the title and the body of the tooltip. Either right, left or justify
tooltipTitle	String	none	title
tooltipTitleColor	String	#ffffff	Color of the title text
tooltipWidth	String	300	Width of tooltip

General Attributes

Attribute	Theme	Data Types	Description
cssClass	simple	String	define html class attribute
cssStyle	simple	String	define html style attribute
title	simple	String	define html title attribute
disabled	simple	String	define html disabled attribute
label	xhtml	String	define label of form element
labelPosition	xhtml	String	define label position of form element (top/left), default to left
requiredposition	xhtml	String	define required label position of form element (left/right), default to right
name	simple	String	Form Element's field name mapping
required	xhtml	Boolean	add * to label (true to add false otherwise)
tabIndex	simple	String	define html tabindex attribute
value	simple	Object	define value of form element

When Some Attributes Don't Apply

Note that some tags don't don't have any templates that utilize certain attributes, either because it doesn't make sense or it isn't required. For example, the form tag, while it supports the tabindex attribute, none of the themes render it out. Also, as mentioned, certain themes won't utilize some attributes.

Value/Name Relationship

In many of the tags, except for the form tag, there is a unique relationship between the name and value attributes. The nameattribute is what the form element gets named and eventually submitted as. This effectively is the expression to which you wish to bind the incoming value to. In most cases, it is a simple JavaBean property, such as "firstName". This would eventually call setFirstName().

Similarly, you often wish to also display in your form elements existing data from the same JavaBean property. This time, the attributevalue is used. A value of "%{firstName}" would call getFirstName() and display it in your form, allowing users to edit the value and re-submit it.

<@ww.form action="updatePerson">
    <@ww.textfield label="First name" name="firstName" value="%{firstName}"/>
    ...
</@ww.form>

However, because the relationship between name and value is so often predictable, we automatically do this for you, allowing you to do:

<@ww.form action="updatePerson">
    <@ww.textfield label="First name" name="firstName"/>
    ...
</@ww.form>

While most attributes are exposed to the underlying templates as the same key as the attribute (ie: ${parameters.label}), the valueattribute is not. Instead, it can be accessed via the "nameValue" key (ie: ${parameters.nameValue}) to indicate that it may have been generated from the name attribute rather than explicitly defined in the value attribute.

ID Name Assignment

All form tags automatically assign an ID for you. You are free to override this ID if you wish. The ID assignment works as follows:

Required Attribute

The "required" attribute on many WebWork UI tags defaults to true only if you have client side validation enabled and there is a validator associated with that particular field.

Tooltip

Every Form UI component (in xhtml / css_xhtml or any others that extends of them) could have tooltip assigned to a them. The Form component's tooltip related attribute once defined will be applicable to all form UI component that is created under it unless explicitly overriden by having the Form UI component itself defined that tooltip attribute.

In Example 1, the textfield will inherit the tooltipAboveMousePointer attribte from its containing form. In other words, although it doesn't defined a tooltipAboveMousePointer attribute, it will have that attribute defined as true inherited from its containing form.

In Example 2, the the textfield will inherite both the tooltipAboveMousePointer and tooltipLeftOfMousePointer attribute from its containing form but tooltipLeftOfMousePointer attribute is overriden at the textfield itself. Hence, the textfield actually will have tooltipAboveMousePointer defined as true, inherited from its containing form and tooltipLeftOfMousePointer defined as false, due to overriden at the textfield itself.

Example 3, 4 and 5 shows different way of setting the tooltipConfig attribute.
Example 3:Set tooltip config through body of param tag
Example 4:Set tooltip config through value attribute of param tag
Example 5:Set tooltip config through tooltipConfig attribute of component tag

<!-- Example 1: -->
<ww:form
			tooltipConfig="#{'tooltipAboveMousePointer':'true',
                          'tooltipBgColor='#eeeeee'}" .... >
  ....
    <ww:textfield label="Customer Name" tooltip="Enter the customer name" .... />
  ....
</ww:form>

<!-- Example 2: -->
<ww:form
        tooltipConfig="#{'tooltipAboveMousePointer':'true',
         				 'tooltipLeftOfMousePointer':'true'}" ... >
  ....
    <ww:textfield label="Address"
         tooltip="Enter your address"
         tooltipConfig="#{'tooltipLeftOfMousePointer':'false'}" />
  ....
</ww:form>


<-- Example 3: -->
<ww:textfield
       label="Customer Name"
      tooltip="One of our customer Details'">
       <ww:param name="tooltipConfig">
            tooltipWidth = 150 |
            tooltipAboveMousePointer = false |
            tooltipLeftOfMousePointer = false
       </ww:param>
</ww:textfield>


<-- Example 4: -->
<ww:textfield
        label="Customer Address"
        tooltip="Enter The Customer Address" >
        <ww:param
             name="tooltipConfig"
             value="#{'tooltipStatic':'true',
                      'tooltipSticky':'true',
                      'tooltipAboveMousePointer':'false',
                      'tooltipLeftOfMousePointer':'false'}"  />
</ww:textfield>


<-- Example 5: -->
<ww:textfield
         label="Customer Telephone Number"
         tooltip="Enter customer Telephone Number"
         tooltipConfig="#{'tooltipBgColor':'#cccccc',
                          'tooltipFontColor':'#eeeeee',
                          'tooltipAboveMousePointer':'false',
                          'tooltipLeftOfMousePointer':'false'}" /<

Description